home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / etc / Fs_Dispatch.man < prev    next >
Text File  |  1989-01-27  |  5KB  |  141 lines
  1. '\" Copyright 1989 Regents of the University of California
  2. '\" Permission to use, copy, modify, and distribute this
  3. '\" documentation for any purpose and without fee is hereby
  4. '\" granted, provided that this notice appears in all copies.
  5. '\" The University of California makes no representations about
  6. '\" the suitability of this material for any purpose.  It is
  7. '\" provided "as is" without express or implied warranty.
  8. '\" 
  9. '\" $Header: /sprite/src/lib/c/etc/RCS/Fs_Dispatch.man,v 1.3 89/01/27 08:37:01 ouster Exp $ SPRITE (Berkeley)
  10. '\" 
  11. .so \*(]ltmac.sprite
  12. .HS Fs_Dispatch lib
  13. .BS
  14. .SH NAME
  15. Fs_Dispatch, Fs_EventHandlerCreate, Fs_EventHandlerDestroy, Fs_EventHandlerData,
  16. Fs_EventHandlerChangeData, Fs_TimeoutHandlerCreate, Fs_TimeoutHandlerDestroy \- stream event and timeout dispatcher routines.
  17. .SH SYNOPSIS
  18. .nf
  19. \fB#include <fs.h>\fR
  20.  
  21. void 
  22. \fBFs_Dispatch\fR()
  23.  
  24. void 
  25. \fBFs_EventHandlerCreate\fR(\fIstreamID, eventMask, proc, clientData\fP)
  26.  
  27. void 
  28. \fBFs_EventHandlerDestroy\fR(\fIstreamID\fP)
  29.  
  30. void 
  31. \fBFs_EventHandlerData\fR(\fIstreamID\fP)
  32.  
  33. ClientData 
  34. \fBFs_EventHandlerChangeData\fR(\fIstreamID, clientData\fP)
  35.  
  36. \fB#include <time.h>\fR
  37.  
  38. Fs_TimeoutHandler 
  39. \fBFs_TimeoutHandlerCreate\fR(\fItime, relativeTime, proc, clientData\fP)
  40.  
  41. void 
  42. \fBFs_TimeoutHandlerDestroy\fR(\fPtoken\fP)
  43.  
  44. .SH ARGUMENTS
  45. .AS Fs_TimeoutHandler relativeTime
  46. .AP int streamID in
  47. Specifies the stream to create an event handler for.
  48. .AP int eventMask in
  49. Mask indicating which events on \fIstreamID\fP are to be processed 
  50. by \fIproc\fP. Can be the bitwise OR of \fBFS_READABLE\fR, \fBFS_WRITABLE\fR and
  51. \fBFS_EXCEPTION\fR.
  52. .AP void (*proc)() in
  53. Procedure to invoke when one of the events in \fIeventMask\fP occurs on a 
  54. stream or when a timeout period expires.
  55. .AP ClientData clientData in
  56. Uninterpreted value passed to \fIproc\fP when it is invoked.
  57. .AP Time time in
  58. The absolute time when \fIproc\fP should be called or the time interval
  59. between calls to \fIproc\fP.
  60. .AP Boolean relativeTime in
  61. If \fBTRUE\fR, then \fItime\fP specifies a interval between calls to \fIproc\fP.
  62. If \fBFALSE\fR, then \fItime\fP specifies the absolute time when \fIproc\fP should
  63. be called.
  64. .AP Fs_TimeoutHandler token in
  65. A token to identify a particular timeout handler so it can be destroyed.
  66. .BE
  67. .SH DESCRIPTION
  68. These routines implement a dispatcher for events on streams and
  69. timeouts. An event occurs when the stream becomes readable, writable or
  70. has an exception condition pending. The dispatcher handles the 
  71. details of waiting for events to
  72. occur on streams. When an event occurs, the dispatcher calls a routine
  73. supplied by the clients to deal with the event. Also, timeout handlers can
  74. be created so that a client-supplied routine can be called at a
  75. specific time or at regular intervals.
  76. .PP
  77. The dispatcher must be initialized by calling \fBFs_EventHandlerCreate\fR and/or
  78. \fBFs_TimeoutHandlerCreate\fR before \fBFs_Dispatch\fR is called.
  79. \fBFs_Dispatch\fR causes the process to wait until an event occurs on a stream 
  80. or until a time-out occurs. 
  81. At that point, it calls the appropriate handler. Once the handler completes,
  82. \fBFs_Dispatch\fR returns to its caller. To have the dispatcher remain in control,
  83. do
  84. .DS
  85.     while (TRUE) {
  86.     Fs_Dispatch();
  87.     }
  88. .DE
  89. .PP
  90. \fBFs_EventHandlerCreate\fR is used to cause the procedure \fIproc\fP to be 
  91. called when one or more of the events in \fIeventMask\fP occur 
  92. on \fIstreamID\fP. Only one procedure may be attached to a stream so 
  93. it should be able to deal with all of the event types. 
  94. \fIProc\fP should be declared as:
  95. .DS
  96. void
  97. proc(clientData, streamID, eventMask)
  98.     ClientData    clientData;
  99.     int        streamID;
  100.     int        eventMask;
  101. { 
  102. }
  103. .DE
  104. \fBFs_EventHandlerData\fR can be used to get the \fIclientData\fP associated with
  105. \fIstreamID\fP. 
  106. \fBFs_EventHandlerChangeData\fR can be used to change the \fIclientData\fP 
  107. associated with \fIstreamID\fP. 
  108. The handler can be destroyed with \fBFs_EventHandlerDestroy\fR.
  109. .PP
  110. In addition, a time-out routine can be setup to be called using
  111. \fBFs_TimeoutHandlerCreate\fR. If \fIrelativeTime\fP is \fBTRUE\fR, then \fItime\fP 
  112. specifies an interval (e.g. one hour) 
  113. from the current time that \fIproc\fP will be called at.
  114. When \fIproc\fP returns, it will automatically be rescheduled to be called 
  115. at the next interval. If \fIproc\fP doesn't need to be called again, it should
  116. call \fBFs_TimeoutHandlerDestroy\fR.
  117. If \fIrelativeTime\fP is \fBFALSE\fR, then \fItime\fP specifies a specific time
  118. (e.g., 3:15pm 17 Sept. 1987)
  119. that \fIproc\fP will be called at. \fIProc\fP is called once \(em it is not
  120. automatically rescheduled to be called again. However, it could call
  121. \fBFs_TimeoutHandlerCreate\fR to cause it to be called again.
  122. \fIProc\fP should be declared as:
  123. .DS
  124. void
  125. proc(clientData, time)
  126.     ClientData    clientData;
  127.     Time    Time;
  128. { 
  129. }
  130. .DE
  131. For example, to have \fBExampleRoutine\fR called in 1 minute from now and every
  132. minute after that, the call should be:
  133. .DS
  134.   Fs_TimeoutHandlerCreate(time_OneMinute, TRUE, ExampleRoutine, clientData);
  135. .DE
  136. \fBFs_TimeoutHandlerCreate\fR returns a token that must be saved 
  137. if \fBFs_TimeoutHandlerDestroy\fR is to be called.
  138.  
  139. .SH KEYWORDS
  140. callback, client data, dispatcher, stream ID, time
  141.